 /*******************************************************************************
  * Copyright (c) 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  ******************************************************************************/

 package org.eclipse.ui.navigator;

 /**
  *
  * Performs calculations that are necessary to determine the correct children to
  * render in the viewer.
  *
  * <p>
  * This interface is not intended to be implemented by clients.
  * </p>
  *
  * @see INavigatorContentService#getPipelineService()
  * @see PipelinedShapeModification
  * @see PipelinedViewerUpdate
  * @see IPipelinedTreeContentProvider
  * @since 3.2
  */
 public interface INavigatorPipelineService {
     

     /**
      * Intercept attempts to add elements directly to the viewer.
      *
      * <p>
      * For content extensions that reshape the structure of children in a
      * viewer, their overridden extensions may sometimes use optimized refreshes
      * to add elements to the tree. These attempts must be intercepted and
      * mapped to the correct set of model elements in the overridding extension.
      * Clients may add, remove, or modify elements in the given set of added
      * children. Clients should return a set for downstream extensions to
      * massage further.
      * </p>
      * <p>
      * <b>Clients should not call any of the add, remove, refresh, or update
      * methods on the viewer from this method or any code invoked by the
      * implementation of this method.</b>
      * </p>
      *
      * @param anAddModification
      * The shape modification which contains the current suggested
      * parent and children. Clients may modify this parameter
      * directly and return it as the new shape modification.
      * @return The new shape modification to use. Clients should <b>never</b>
      * return <b>null</b> from this method.
      */
     public PipelinedShapeModification interceptAdd(
             PipelinedShapeModification anAddModification);
     
     /**
      * Intercept attempts to remove elements directly from the viewer.
      *
      * <p>
      * For content extensions that reshape the structure of children in a
      * viewer, their overridden extensions may sometimes use optimized refreshes
      * to remove elements to the tree. These attempts must be intercepted and
      * mapped to the correct set of model elements in the overridding extension.
      * Clients may add, remove, or modify elements in the given set of removed
      * children. Clients should return a set for downstream extensions to
      * massage further.
      * </p>
      * <p>
      * <b>Clients should not call any of the add, remove, refresh, or update
      * methods on the viewer from this method or any code invoked by the
      * implementation of this method.</b>
      * </p>
      *
      * @param aRemoveModification
      * The shape modification which contains the current suggested
      * parent and children. Clients may modify this parameter
      * directly and return it as the new shape modification.
      * @return The new shape modification to use. Clients should <b>never</b>
      * return <b>null</b> from this method.
      */
     public PipelinedShapeModification interceptRemove(
             PipelinedShapeModification aRemoveModification);
     
     /**
      * Intercept calls to viewer <code>refresh()</code> methods.
      *
      * <p>
      * Clients may modify the given update to add or remove the elements to be
      * refreshed. Clients may return the same instance that was passed in for
      * the next downstream extension.
      * </p>
      *
      * <p>
      * <b>Clients should not call any of the add, remove, refresh, or update
      * methods on the viewer from this method or any code invoked by the
      * implementation of this method.</b>
      * </p>
      *
      * @param aRefreshSynchronization
      * The (current) refresh update to execute against the viewer.
      * @return The (potentially reshaped) refresh to execute against the viewer.
      */
     boolean interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization);
     
     /**
      * Intercept calls to viewer <code>update()</code> methods.
      *
      * <p>
      * Clients may modify the given update to add or remove the elements to be
      * updated. Clients may also add or remove properties for the given targets
      * to optimize the refresh. Clients may return the same instance that was
      * passed in for the next downstream extension.
      * </p>
      *
      * <p>
      * <b>Clients should not call any of the add, remove, refresh, or update
      * methods on the viewer from this method or any code invoked by the
      * implementation of this method.</b>
      * </p>
      *
      * @param anUpdateSynchronization
      * The (current) update to execute against the viewer.
      * @return The (potentially reshaped) update to execute against the viewer.
      */
     public boolean interceptUpdate(
             PipelinedViewerUpdate anUpdateSynchronization);

 }

